Skip to main content
POST
/
v1
/
agents
/
{agent_id}
/
invoke
/
async
Invoke Agent (Async)
curl --request POST \
  --url https://api.xpander.ai/v1/agents/{agent_id}/invoke/async \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
  "input": {
    "text": "<string>",
    "files": [
      "<string>"
    ],
    "user": {
      "id": "<string>",
      "first_name": "<string>",
      "last_name": "<string>",
      "email": "<string>",
      "additional_attributes": {}
    }
  },
  "id": "<string>",
  "payload_extension": {},
  "parent_execution_id": "<string>",
  "worker_id": "<string>",
  "source": "<string>",
  "output_format": "text",
  "output_schema": {},
  "run_locally": true,
  "additional_context": "<string>",
  "expected_output": "<string>",
  "events_streaming": true,
  "mcp_servers": [
    {}
  ],
  "triggering_agent_id": "<string>",
  "title": "<string>"
}'
{
  "id": "<string>",
  "agent_id": "<string>",
  "organization_id": "<string>",
  "input": {
    "text": "<string>",
    "files": [
      "<string>"
    ],
    "user": {
      "id": "<string>",
      "first_name": "<string>",
      "last_name": "<string>",
      "email": "<string>",
      "additional_attributes": {},
      "display_name": "<string>"
    }
  },
  "status": "pending",
  "internal_status": "<string>",
  "last_executed_node_id": "<string>",
  "agent_version": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "started_at": "2023-11-07T05:31:56Z",
  "paused_at": "2023-11-07T05:31:56Z",
  "finished_at": "2023-11-07T05:31:56Z",
  "result": "<string>",
  "parent_execution": "<string>",
  "sub_executions": [
    "<string>"
  ],
  "finished_sub_executions": [
    "<string>"
  ],
  "is_manually_stopped": true,
  "payload_extension": {},
  "hitl_request": {
    "operation_id": "<string>",
    "approved_by": "<string>",
    "rejected_by": "<string>",
    "title": "<string>",
    "description": "<string>",
    "content": "<string>"
  },
  "pending_eca_request": {
    "connector_name": "<string>",
    "auth_url": "<string>"
  },
  "source": "<string>",
  "worker_id": "<string>",
  "additional_context": "<string>",
  "expected_output": "<string>",
  "output_format": "text",
  "output_schema": {},
  "events_streaming": true,
  "used_mutating_tools": true,
  "is_continuous": true,
  "mcp_servers": [
    {}
  ],
  "triggering_agent_id": "<string>",
  "title": "<string>"
}
Execute an agent task asynchronously. This endpoint returns immediately with a task ID that can be used to poll for results. Best for long-running tasks or when you need non-blocking execution.

​
Path Parameters

​
agent_id
string
required
Unique identifier of the agent to invoke (UUID format)

​
Request Body

​
input
object
required
Agent execution input containing the task details
​
output_format
string
Desired output format. Valid values: text | json | markdownDefault: text
  • text: Plain text response
  • json: Structured JSON output (use with output_schema for validation)
  • markdown: Formatted markdown response
​
output_schema
object
JSON Schema to validate and structure the agent’s output. When provided with output_format: "json", the agent will return data conforming to this schema.Example:
{
  "type": "object",
  "required": ["name", "email"],
  "properties": {
    "name": {"type": "string"},
    "email": {"type": "string", "format": "email"}
  }
}
​
additional_context
string
Additional context to guide the agent’s behavior. Use this to specify tone, audience, constraints, or background information.Example: "This is for executive leadership. Use professional tone and focus on business impact."
​
expected_output
string
Description of the expected output format, length, or structure. Helps guide the agent to produce the desired result.Example: "A 500-word summary with 3 key recommendations and supporting data."
​
title
string
Human-readable title for the task. Useful for identification and organization in task lists.Example: "Q4 Sales Analysis"
​
parent_execution_id
string
UUID of the parent task if this is a sub-task. Used for multi-agent workflows and task hierarchies.Example: "550e8400-e29b-41d4-a716-446655440000"
​
triggering_agent_id
string
UUID of the agent that triggered this task. Used for tracking agent-to-agent delegation.Example: "7c9e6679-7425-40de-944b-e07fc1f90ae7"
​
payload_extension
object
Custom metadata to attach to the task. Any valid JSON object. Useful for tracking, routing, or application-specific data.Example:
{
  "request_id": "REQ-2025-001",
  "priority": "high",
  "department": "sales",
  "tags": ["urgent", "vip-customer"]
}
​
events_streaming
boolean
Enable detailed event streaming for progress tracking. When true, provides granular events about tool calls and execution steps.Default: falseNote: Only effective when using the /invoke/stream endpoint.
​
mcp_servers
array
Array of Model Context Protocol (MCP) server configurations to use during execution. Enables integration with external tools and services.Example:
[
  {
    "name": "web-search",
    "config": {"provider": "google", "max_results": 10}
  }
]
​
source
string
Identifier for the source system or application that created this task. Useful for analytics and debugging.Example: "mobile-app" | "web-dashboard" | "api-integration"
​
id
string
Custom task ID. If not provided, a UUID will be automatically generated. Use this to map tasks to external system IDs.Example: "custom-task-12345"
​
worker_id
string
Identifier for the worker or process handling this task. Used for distributed execution tracking.
​
run_locally
boolean
Execute the task locally instead of in the cloud. Used for development and testing.Default: false

​
Response

Returns a complete AgentExecution object:
​
id
string
Unique identifier for the created task (UUID) - use this to poll for results
​
agent_id
string
UUID of the agent executing this task
​
organization_id
string
UUID of the organization
​
status
string
Initial task status: pending, executing, completed, failed
​
input
object
The input object that was provided
​
created_at
string
ISO 8601 timestamp of when the task was created
​
result
string
Task result (null until completed)
​
output_format
string
The output format specified
​
output_schema
object
The output schema if provided

​
Example Requests

​
Basic Request

curl -X POST -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "text": "What is the weather in San Francisco?"
    }
  }' \
  https://api.xpander.ai/v1/agents/{agent_id}/invoke/async

​
Structured JSON Output

curl -X POST -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "text": "Extract contact info: John Doe, john@example.com, (555) 123-4567"
    },
    "output_format": "json",
    "output_schema": {
      "type": "object",
      "required": ["name", "email", "phone"],
      "properties": {
        "name": {"type": "string"},
        "email": {"type": "string", "format": "email"},
        "phone": {"type": "string"}
      }
    }
  }' \
  https://api.xpander.ai/v1/agents/{agent_id}/invoke/async

​
File Processing with User Context

curl -X POST -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "text": "Analyze these documents and summarize key findings",
      "files": [
        "https://example.com/report.pdf",
        "https://example.com/data.csv"
      ],
      "user": {
        "id": "user-123",
        "first_name": "Jane",
        "last_name": "Smith",
        "email": "jane.smith@company.com",
        "additional_attributes": {
          "department": "analytics",
          "role": "senior_analyst"
        }
      }
    },
    "title": "Q4 Report Analysis",
    "additional_context": "Focus on year-over-year trends and regional performance",
    "expected_output": "Executive summary with 3-5 key insights"
  }' \
  https://api.xpander.ai/v1/agents/{agent_id}/invoke/async

​
Multi-Agent Workflow

curl -X POST -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "text": "Process this sub-task"
    },
    "parent_execution_id": "parent-task-uuid",
    "triggering_agent_id": "coordinator-agent-uuid",
    "payload_extension": {
      "workflow_id": "WF-2025-001",
      "step": 2,
      "total_steps": 5
    }
  }' \
  https://api.xpander.ai/v1/agents/{agent_id}/invoke/async

​
Advanced: Full Feature Set

curl -X POST -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "text": "Research AI trends and create a presentation",
      "files": [],
      "user": {
        "id": "analyst-001",
        "email": "analyst@company.com"
      }
    },
    "output_format": "markdown",
    "title": "AI Trends Research",
    "additional_context": "Target audience: C-level executives. Professional tone.",
    "expected_output": "10-slide presentation outline with key points",
    "payload_extension": {
      "project_id": "PROJ-2025-042",
      "priority": "high",
      "deadline": "2025-11-15"
    },
    "mcp_servers": [
      {
        "name": "web-search",
        "config": {"provider": "google"}
      }
    ],
    "source": "research-portal"
  }' \
  https://api.xpander.ai/v1/agents/{agent_id}/invoke/async

​
Example Response

{
  "id": "60ce6693-9c4d-45a0-a675-76cd8cbefbac",
  "agent_id": "e9aaf26b-5e8b-42ce-9a96-b32acd9136cb",
  "organization_id": "91fbe9bc-35b3-41e8-b59d-922fb5a0f031",
  "input": {
    "text": "What is 5+5?",
    "files": [],
    "user": null
  },
  "status": "pending",
  "internal_status": null,
  "last_executed_node_id": null,
  "agent_version": null,
  "created_at": "2025-11-06T21:08:55.503495Z",
  "started_at": null,
  "paused_at": null,
  "finished_at": null,
  "result": null,
  "parent_execution": null,
  "sub_executions": [],
  "finished_sub_executions": [],
  "is_manually_stopped": false,
  "payload_extension": null,
  "hitl_request": null,
  "pending_eca_request": null,
  "source": "api",
  "worker_id": null,
  "additional_context": null,
  "expected_output": null,
  "output_format": "text",
  "output_schema": null,
  "events_streaming": false,
  "used_mutating_tools": false,
  "is_continuous": false,
  "mcp_servers": [],
  "triggering_agent_id": null,
  "title": null
}

​
Polling for Results

Use the task ID with the [Get Task](/API reference/v1/tasks/get-task) endpoint to check status and retrieve results: 
# Poll for results (repeat until status is "completed")
curl -H "x-api-key: YOUR_API_KEY" \
  https://api.xpander.ai/v1/tasks/{task_id}

​
See Also

  • [Invoke Agent (Sync)](/API reference/v1/agents/invoke-sync) - For quick tasks that complete in under 30 seconds
  • [Invoke Agent (Stream)](/API reference/v1/agents/invoke-stream) - For real-time streaming responses
  • [Get Task](/API reference/v1/tasks/get-task) - Poll for task status and retrieve results
  • [List Tasks](/API reference/v1/tasks/list-tasks) - Query and filter task history
  • [Get Agent Tasks](/API reference/v1/agents/list-agents) - Get all tasks for a specific agent

Authorizations

​
x-api-key
string
header
required

API Key for authentication

Path Parameters

​
agent_id
string
required

Body

application/json
​
input
object
required
​
id
string | null
​
payload_extension
object | null
​
parent_execution_id
string | null
​
worker_id
string | null
​
source
string | null
​
output_format
enum<string> | null
default:text
Available options:
text,
markdown,
json
​
output_schema
object | null
​
run_locally
boolean | null
default:false
​
additional_context
string | null
​
expected_output
string | null
​
events_streaming
boolean | null
default:false
​
mcp_servers
Mcp Servers · object[] | null
​
triggering_agent_id
string | null
​
title
string | null

Response

Successful Response

Task creation response model.

Extends AgentExecution with additional agent_id field.

​
id
string
required
​
agent_id
string
required
​
organization_id
string
required
​
input
object
required
​
created_at
string<date-time>
required
​
status
enum<string> | null
default:pending
Available options:
pending,
executing,
paused,
error,
failed,
completed,
stopped
​
internal_status
string | null
​
last_executed_node_id
string | null
​
agent_version
string | null
​
started_at
string<date-time> | null
​
paused_at
string<date-time> | null
​
finished_at
string<date-time> | null
​
result
string | null
​
parent_execution
string | null
​
sub_executions
string[] | null
​
finished_sub_executions
string[] | null
​
is_manually_stopped
boolean | null
default:false
​
payload_extension
object | null
​
hitl_request
object | null
​
pending_eca_request
object | null
​
source
string | null
​
worker_id
string | null
​
additional_context
string | null
​
expected_output
string | null
​
output_format
enum<string> | null
default:text
Available options:
text,
markdown,
json
​
output_schema
object | null
​
events_streaming
boolean | null
default:false
​
used_mutating_tools
boolean | null
default:false
​
is_continuous
boolean | null
default:false
​
mcp_servers
Mcp Servers · object[] | null
​
triggering_agent_id
string | null
​
title
string | null